home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / cmds / tx.man < prev    next >
Encoding:
Text File  |  1990-08-11  |  18.3 KB  |  464 lines

  1. '\" Copyright 1989 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/src/cmds/tx/RCS/tx.man,v 1.15 90/08/10 17:50:20 shirriff Exp $ SPRITE (Berkeley)
  10. '
  11. .so \*(]ltmac.sprite
  12. .HS TX cmds
  13. .BS
  14. .SH NAME
  15. tx \- Scrollable terminal emulator for X
  16. .SH SYNOPSIS
  17. \fBtx \fR[\fIoptions\fR]
  18. .SH OPTIONS
  19. .IP "\fB\-bd \fIcolor\fR" 15
  20. Use \fIcolor\fR as the border color for the window.  If this switch
  21. isn't given then the \fBborderColor\fR X default is used.  If it isn't given
  22. either, then the foreground color is used.
  23. .IP "\fB\-bg \fIcolor\fR" 15
  24. Use \fIcolor\fR as the background color for the window.  If this switch
  25. isn't given then the \fBbackground\fR X default is used.  If it isn't given
  26. either, or if the display is a black-and-white one, then White is used.
  27. .IP "\fB\-D\fR" 15
  28. .VS
  29. Causes \fBtx\fR not to detach itself from its parent process.
  30. .IP "\fB\-display \fIhost\fB:\fIdisplay\fR" 15
  31. .VS
  32. Use \fIhost\fR and \fIdisplay\fR as an indication of the
  33. display on which to open the window.  The display defaults to the
  34. one specified in the \fBDISPLAY\fR environment variable.
  35. .VE
  36. .IP "\fB\-fg \fIcolor\fR" 15
  37. Use \fIcolor\fR as the foreground color for the window.  If this switch
  38. isn't given then the \fBforeground\fR X default is used.  If it isn't given
  39. either, or if the display is a black-and-white one, then Black is used.
  40. .IP "\fB\-fn \fIfont\fR" 15
  41. Use \fIfont\fR as the font for the window.  If this switch isn't given,
  42. then the \fBfont\fR X default is used as the font.  If it isn't given
  43. either, then the Sx default font is used.
  44. .IP "\fB\-geometry \fIgeometry\fR" 15
  45. .VS
  46. Use \fIgeometry\fR as the geometry for the window.  If no geometry
  47. is specified on the command line, it the geometry defaults to the value of the
  48. \fBgeometry\fR X default.  If no default is specified, then
  49. \fBtx\fR picks a geometry.
  50. .IP \fB\-help\fR
  51. Print out a list of the command-line options (and brief descriptions
  52. of their functions) and exit without opening a window.
  53. .VE
  54. .IP "\fB\-icon \fIfile\fR" 15
  55. \fIFile\fR is the name of a file in bitmap format.  Read the file and
  56. use it as the icon for the window.  If \fIfile\fR is \fBlocalhost\fR,
  57. then \fBtx\fR chooses the default icon file corresponding to the local host.
  58. .IP "\fB\-ix \fIxcoord\fR" 15
  59. Display the icon at x-coordinate \fIxcoord\fR.
  60. .IP "\fB\-iy \fIycoord\fR" 15
  61. Display the icon at y-coordinate \fIycoord\fR.
  62. .IP "\fB\-sb \fIcolor\fR" 15
  63. Use \fIcolor\fR as the background color for the window's scrollbar.
  64. If this switch isn't given then the \fBscrollbar.background\fR
  65. X default is used.  If it isn't given either, then the background
  66. color for the text window is used.
  67. .IP "\fB\-se \fIcolor\fR" 15
  68. Use \fIcolor\fR as the color for the window's scrollbar elevator.
  69. If this switch isn't given then the \fBscrollbar.elevator\fR
  70. X default is used.  If it isn't given either, then the background
  71. color for the text window is used.
  72. .IP "\fB\-sf \fIcolor\fR" 15
  73. Use \fIcolor\fR as the foreground color for the window's scrollbar.
  74. If this switch isn't given then the \fBscrollbar.foreground\fR
  75. X default is used.  If it isn't given either, then the foreground
  76. color for the text window is used.
  77. .IP "\fB\-showtitle\fR" 15
  78. .VS
  79. Display a title bar at the top of the window.  Tx normally assumes
  80. that a window manager will display a title bar;  if your window
  81. manager doesn't, you may wish to use this switch.  If this switch
  82. isn't specified, then Tx checks for a \fBshowTitle\fR X default;
  83. if it exists and contains the string ``yes'', then a title
  84. bar will be displayed.
  85. .VE
  86. .IP "\fB\-tb \fIcolor\fR" 15
  87. Use \fIcolor\fR as the background color for the window's title bar.
  88. If this switch isn't given then the \fBtitle.background\fR
  89. X default is used.  If it isn't given either, then the background
  90. color for the text window is used.  This option is ignored if
  91. Tx isn't displaying a title bar.
  92. .IP "\fB\-tf \fIcolor\fR" 15
  93. Use \fIcolor\fR as the foreground color for the window's title bar.
  94. If this switch isn't given then the \fBtitle.foreground\fR
  95. X default is used.  If it isn't given either, then the foreground
  96. color for the text window is used.  This option is ignored if
  97. Tx isn't displaying a title bar.
  98. .IP "\fB\-ts \fIcolor\fR" 15
  99. Use \fIcolor\fR as the color for the window's title stripes.
  100. If this switch isn't given then the \title.stripe\fR
  101. X default is used.  If it isn't given either, then the foreground
  102. color for the text window is used.  This option is ignored if
  103. Tx isn't displaying a title bar.
  104. .IP "\fB\-title \fIname\fR" 15
  105. Display \fIname\fR in the title bar for the window.  The default title
  106. is the name of the pseudo-terminal associated with the window.
  107. .IP "\fB=\fIgeometry\fR" 15
  108. Use \fIgeometry\fR as the geometry specifier for the window (same effect
  109. as the \fB\-geometry option).
  110. .IP "\fIhost:display\fR" 15
  111. Use this argument to select the display on which to create the window
  112. (same effect as the \fB\-display\fR option).
  113. .IP "\fB\-e \fIcommand\fP" 15
  114. This switch must be the last one, if it is present.  The arguments following
  115. the \fB\-e\fR switch constitute
  116. the command to execute in the window.
  117. \fICommand\fR is run using the terminal emulator for
  118. standard input and standard output.  When the command completes, the window
  119. will be destroyed and \fBtx\fR will exit.  The default command is ``/bin/csh -i'',
  120. or if a SHELL environment variable is defined, then it is invoked with a -i
  121. argument.
  122. .BE
  123. .SH INTRODUCTION
  124. \fBTx\fR is a terminal emulator that uses the facilities of the X window
  125. system, the Sx supplementary library, and the Tcl command interpreter.
  126. It executes a command
  127. (usually a shell) and arranges for the command's standard input and
  128. standard output streams to be directed from/to a pseudo-terminal controlled
  129. by \fBtx\fR.  \fBTx\fR, in turn, displays a scrollable window in more-or-less the
  130. same way as \fBmx\fR;  output from the application is displayed in the window
  131. and keystrokes typed in the window are passed through to the application.
  132. \fBTx\fR windows emulate a very simple terminal with enough facilities to run
  133. programs like vi.
  134. .LP
  135. The implementation of \fBtx\fR is very similar to that of \fBmx\fR;  it shares
  136. much of the code and many of the commands.  You should read the \fBmx\fR
  137. manual page before reading this one, in order to learn about the basic
  138. command interface and the \fBmx\fR commands.  \fBTx\fR commands that are identical
  139. to \fBmx\fR commands are not documented here except by reference to the \fBmx\fR
  140. manual page.
  141.  
  142. .SH ".TX FILES"
  143. After processing command line options and opening the window,
  144. \fBtx\fR checks for the existence of a file ``.tx'' in your
  145. home directory (environment variable HOME).  If the file exists, \fBtx\fR
  146. reads it in and processes it as a command file, just as if it were read
  147. with the \fBsource\fP command.  Then it checks for a .tx file in the
  148. current directory, and processes it if it exists.
  149.  
  150. .SH SELECTION
  151. Selection in \fBtx\fR is identical to that in \fBmx\fR, except for one difference.
  152. In \fBtx\fR the caret always appears at the end of the typescript, except
  153. when the typescript is in vi mode (see the \fBvi\fR command);  there
  154. is no way to reposition the caret with the mouse.
  155.  
  156. .SH "VARIABLES"
  157. See the \fBmx\fR manual page for overall information.  The special
  158. variables defined by \fBtx\fR are:
  159. .RS
  160. .TP
  161. \fBargs\fP
  162. Set by \fBtx\fR to hold the arguments to the current variable being executed, if any.
  163. .TP
  164. \fBheight\fP
  165. Set by \fBtx\fR to hold the
  166. height of the window, in lines of text.  If the last line
  167. appearing in the window is only partially visible, it doesn't count.
  168. .TP
  169. \fBsearchCmd\fP
  170. When the middle button is clicked in the ``Search'' string entry, or when
  171. carriage-return is typed there, the contents of this variable are
  172. executed as a command.
  173. .TP
  174. \fBsearchString\fP
  175. Set by \fBtx\fR to hold the contents of the search entry subwindow.
  176. .TP
  177. \fBtermcap\fP
  178. Set by \fBtx\fR to hold a
  179. termcap entry that provides enough functionality to run Vi and other
  180. prehistoric screen-based programs.  It's based on a terminal type ``tx''.
  181. This variable is automatically reset whenever the window changes size.
  182. .TP
  183. \fBversion\fR
  184. .VS
  185. Set by \fBtx\fR to hold a version number in the form \fIx.y\fR, where
  186. changes in \fIx\fR correspond to major revisions with probable
  187. incompatibilities, and changes in \fIy\fR represent small bug fixes
  188. and upgrades that should not cause substantial compatibility problems.
  189. .VE
  190. .TP
  191. \fBwidth\fP
  192. Set by \fBtx\fR to hold the
  193. width of the window, in characters.  If the last character position
  194. is only partially-visible, then it doesn't count.  If a variable-width
  195. font is being used, the average character size is used in computing
  196. the window's width.
  197. .TP
  198. \fBwindowId\fR
  199. Set by \fBtx\fR to hold the X window identifier for this window.
  200. .RE
  201.  
  202. .SH "MARKS"
  203. See the \fBmx\fR manual page for documentation.  The same special marks are
  204. defined in \fBtx\fR as in \fBmx\fR.
  205.  
  206. .SH "COMMANDS"
  207. \fBTx\fR is based around the Tcl interpreter just as \fBmx\fR is.  Each keystroke
  208. or menu selection is bound to a Tcl command string, which is passed to
  209. the Tcl interpreter for execution.  See the Tcl man page for details
  210. on the built-in commands provided by Tcl.  In addition to them, \fBtx\fR
  211. provides the following additional built-in commands.  Many of them
  212. are identical to the corresponding commands in \fBmx\fR.
  213. .TP
  214. \fBbind \fR[\fIsequence\fR [\fIcommand\fR]]
  215. Same as in \fBmx\fR.
  216. .TP
  217. \fBcaret \fIoperand\fR
  218. Same as in \fBmx\fR.
  219. .TP
  220. \fBcontrol \fIoption string\fR
  221. .VS
  222. Same as in \fBmx\fR.
  223. .VE
  224. .TP
  225. \fBdelete\fI mark1 \fR[\fImark2\fR]
  226. Same as in \fBmx\fR.
  227. .TP
  228. \fBescape \fIoption\fR\fR
  229. If \fIoption\fR is \fBon\fR, this command enables escape sequences
  230. in window output:  whenever \fBtx\fR finds an escape character (33\s-2\d8\u\s+2)
  231. in the stream of characters output to the pseudo-device for display in
  232. the window, it discards the escape sequence and interprets
  233. the following characters (up to and including the next newline character)
  234. as a \fBtx\fR command rather than characters to be displayed in the window.
  235. If \fIoption\fR is \fBoff\fR, escape sequences are disabled:  they will
  236. be output to the window just like any other characters.  Escape sequences
  237. are enabled by default in \fBtx\fR, and must be enabled for the TERMCAP mechanisms
  238. to work.  This command is most useful to temporarily disable escape-processing
  239. while running programs that generate meaningless escape sequences.
  240. .TP
  241. \fBextract\fI mark1 \fR[\fImark2\fR]
  242. Same as in \fBmx\fR.
  243. .TP
  244. \fBfocus \fIwindow \fR[\fBclear\fR]
  245. Same as in \fBmx\fR.
  246. .TP
  247. \fBgeometry \fIspec\fR
  248. Same as in \fBmx\fR.
  249. .TP
  250. \fBinsert\fR \fIbytes\fR \fIbytes\fR ...
  251. Send \fIbytes\fR to the application as keyboard input on the pty.  If
  252. more than one \fIbytes\fR argument is supplied, each is input in turn,
  253. with a single space between them.
  254. .TP
  255. \fBmark\fI src op args\fR
  256. Same as in \fBmx\fR.
  257. .TP
  258. \fBmenu\fI option args\fR
  259. Same as in \fBmx\fR.
  260. .TP
  261. \fBmessage\fI string\fR
  262. Same as in \fBmx\fR.
  263. .TP
  264. \fBmxopen \fR[\fIoptions\fR] \fIfile file ...\fR
  265. .VS
  266. Same as \fBopen\fR command in in \fBmx\fR.  Used to create an \fBmx\fR
  267. window from \fBtx\fR, e.g. to display variable values.
  268. .TP
  269. \fBmxsend \fIwindow command\fR
  270. Same as in \fBsend\fR command in \fBmx\fR.  Used to send commands to
  271. \fBmx\fR windows created from \fBtx\fR.
  272. .VE
  273. .TP
  274. \fBopen\fR [\fIoptions\fR]
  275. .VS
  276. Open a new \fBtx\fR window.  The \fIoptions\fR to this command are exactly
  277. the same as the command-line options for the \fBtx\fR program, with
  278. the following exceptions.  If the \fB\-e\fR switch is given, then
  279. a new typescript is
  280. created and all the remaining arguments to \fBopen\fR are used as a
  281. command name and arguments for the top-level application in
  282. the new typescript.  If the \fB\-e\fR option is not given, then the new
  283. window will provide an alternate view on the same typescript as the
  284. invoking window.  The \fB\-D\fR
  285. option is not permitted, nor are options that specify a display.
  286. If no geometry specification is given in
  287. \fIoptions\fR, then \fBtx\fR uses the contents of the global variable
  288. \fBgeometry\fP as a default geometry;  if no \fBgeometry\fP variable
  289. exists, then \fBtx\fR picks a default geometry.
  290. Other options, such
  291. as foreground color and font, default to the values from the invoking
  292. window, rather than looking for X defaults.
  293. .VE
  294. \fBOpen\fR sets the global variable \fBnewWindow\fR
  295. to hold the id of the newly-created window.  This may be used in
  296. conjunction with the \fBsend\fR command to issue commands to the
  297. new window.  The return value is always an empty string.
  298. .TP
  299. \fBoutput \fIbytes\fR
  300. Insert \fIbytes\fR in the output display as if they had been output
  301. by the application.
  302. .TP
  303. \fBquit\fR
  304. Destroy the \fBtx\fR window and end the program.
  305. .TP
  306. \fBquote\fR
  307. .VS
  308. Same as in \fBmx\fR.
  309. .VE
  310. .TP
  311. \fBsearch \fR[\fIdirection \fR[\fIpattern\fR]]
  312. Same as in \fBmx\fR.
  313. .TP
  314. \fBsee \fImark\fP [\fBtop\fR|\fBcenter\fR|\fBbottom\fR]
  315. Same as in \fBmx\fR.
  316. .TP
  317. \fBselection \fIoption \fR[\fIarg ...\fR]
  318. Same as in \fBmx\fR.
  319. .TP
  320. \fBsend \fIwindow command\fR
  321. Same as in \fBmx\fR.
  322. .TP
  323. \fBtitle \fIleft center right wmName\fR
  324. .VS
  325. Change the title information for the window.  \fILeft\fR will be
  326. displayed at the left side of the title bar, \fIcenter\fR in the
  327. middle of the bar, and \fIright\fR at the right side of the title
  328. bar.  If any of these three arguments is an empty string, then
  329. nothing will be displayed in the corresponding position.  The
  330. string given by \fIwmName\fR will be recorded as the window's
  331. name for the window manager.  This name will probably appear when
  332. the window is iconified, for example.  If Tx isn't displaying a title
  333. for the window, then only the \fIwmName\fR argument will be used.
  334. .VE
  335. .TP
  336. \fBupdate\fR
  337. Same as in \fBmx\fR.
  338. .TP
  339. \fBvi \fIoption args\fR
  340. This command provides an alternate mode of operation, called ``vi mode'',
  341. which provides sufficient terminal emulation to run the vi editor.  When
  342. the window is in vi mode, an additional window-full of blank lines  (called
  343. the \fIvi area\fR) is
  344. added at the beginning (top) of the typescript, and the view is shifted
  345. to display those lines.  Most of the \fBvi\fR commands are used only
  346. in the crude termcap entry that \fBtx\fR provides for itself.  The
  347. \fBvi\fR command must have one of the following forms:
  348. .RS
  349. .TP
  350. \fBvi enter\fR
  351. Enter vi mode.  Fill the vi area with blank lines, change the window's
  352. view to display those lines, and move the caret to position 0.0.
  353. .TP
  354. \fBvi leave\fR
  355. Leave vi mode.  Delete the lines in the vi area,
  356. move the caret back to the end of the typescript, and change the window's
  357. view to display the end of the typescript.
  358. .TP
  359. \fBvi cd\fR
  360. Clear all the lines on the screen at or below the caret position, leaving
  361. the caret at the beginning of its (now-blank) line.  This command is
  362. provided primarily for emulating the \fBcd\fR termcap entry.
  363. .TP
  364. \fBvi ce\fR
  365. Clear from the caret position to the end of the line, leaving the caret
  366. where it is.  This command is provided primarily for emulating the \fBce\fR
  367. termcap entry.
  368. .TP
  369. \fBvi clear\fR
  370. Clear the lines in the vi area and move the caret to the home position
  371. (0.0).
  372. .TP
  373. \fBvi cursor\fI lineIndex charIndex\fR
  374. Set the caret position to line \fIlineIndex\fR, character \fIcharIndex\fR.
  375. This position must lie within the via area.
  376. .TP
  377. \fBvi deleteline\fR
  378. Delete the line containing the caret, and add a new line to the bottom
  379. of the vi area to keep the total number of lines in the via area constant.
  380. .TP
  381. \fBvi insertline\fR
  382. Add a new blank line to the vi area, just before the caret (the caret
  383. should be at the beginning of a line).  Delete the last line in the vi
  384. area, in order to keep the total number of lines in the vi area constant.
  385. .TP
  386. \fBvi on\fR
  387. Returns a non-zero string if the window is currently in vi mode,
  388. and a zero string otherwise.
  389. .TP
  390. \fBvi tab\fR
  391. Move the caret to the next tab stop.
  392. .TP
  393. \fBvi up\fR
  394. Move the caret up one line.
  395. .TP
  396. \fBvi vt100 \fImode\fR
  397. .VS
  398. If mode is nonzero, tx enters vt100 emulation mode.  If mode is zero,
  399. tx exits vt100 emulation mode.  Not all vt100 functions are emulated.
  400. .VE
  401. .RE
  402.  
  403. .SH "COMMAND PROCEDURES"
  404. .VS
  405. In addition to the built-in commands described above, a number of Tcl
  406. command procedures are created by the default \fBtx\fR startup file.  They
  407. may be invoked just like built-in commands, and are described below.
  408. .TP
  409. \fBshowBindings \fIbinding binding ...\fR
  410. Same as in \fBmx\fR.
  411. .TP
  412. \fBshowMenus \fIname name ...\fR
  413. Same as in \fBmx\fR.
  414. .TP
  415. \fBshowProcs \fIname name ...\fR
  416. Same as in \fBmx\fR.
  417. .TP
  418. \fBshowVars \fIname name ...\fR
  419. Same as in \fBmx\fR.
  420. .TP
  421. \fBwhere\fR
  422. Same as in \fBmx\fR.
  423. .VE
  424.  
  425. .SH "TERMCAP INFORMATION"
  426. \fBTx\fR stores an up-to-date termcap entry in the \fBtermcap\fR variable, and
  427. initializes the TERM and TERMCAP environment variables when it
  428. starts up, so that
  429. you can run programs that use termcap information.  If you change the
  430. size of a \fBtx\fR window, \fBtx\fR will update the \fBtermcap\fR variable
  431. and invoke the TIOCSWINSZ ioctl to notify the application, but
  432. it cannot update the TERM and TERMCAP environment variables in the
  433. application;  you can use the ``Set Termcap'' menu entry to invoke
  434. shell commands to update TERM and TERMCAP.
  435. If you use \fBtx\fR to rlogin to a different machine, most machines
  436. have never heard of \fBtx\fR so they don't have entries for it in their
  437. /etc/termcap files.  There are two possible solutions to this problem:
  438. a) you can invoke the ``Set Termcap'' menu entry after you've gotten
  439. logged in to the remote machine;  b) you can use the \fItxinfo\fR
  440. program as part of your .login shell script, in order to set up the
  441. TERMCAP automatically.  See the manual page for \fItxinfo\fR for
  442. details.
  443.  
  444. .SH "COMMAND SUBWINDOW"
  445. Same as in \fBmx\fR.
  446.  
  447. .SH "MULTIPLE WINDOWS ON SAME TYPESCRIPT"
  448. The \fBopen\fR command may be used to open several windows on the
  449. same typescript.  The windows behave identically except for
  450. one thing: window size.  There is a single window size associated
  451. with the typescript, which is returned when applications perform
  452. TIOCGWINSZ ioctl operations on the pseudo-terminal.  If the different
  453. windows have different sizes, then Tx always uses the size from
  454. a particular one of the windows (usually the first window created on the
  455. typescript).  The other windows are labelled
  456. \fBAlternate\fR at the right side of their title bars
  457. to indicate that their sizes will not be reflected to the application.
  458.  
  459. .SH "SEE ALSO"
  460. mx, txcmd, txinfo
  461.  
  462. .SH KEYWORDS
  463. mouse, terminal emulator, typescript, window
  464.